<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <title></title>
   
</head>
  <body>
         <br>
                 
<table cellpadding="0" cellspacing="8" border="0" width="20%">
           <tbody>
             <tr>
               <td valign="middle" bgcolor="#ccccff"><small><a href="Server.html">
              BACK</a></small></td>
               <td valign="middle" bgcolor="#ccccff"><small><a href="index.html">
              INDEX</a></small></td>
               <td valign="middle" bgcolor="#ccccff"><small><a href="..">
    EXIT</a></small></td>
               <td valign="middle" bgcolor="#ccccff"><small><a href="XmlConfiguration.html">
              NEXT</a></small></td>
             </tr>
                                   
  </tbody>         
</table>
                  
<h1>Logging and Debugging&nbsp;</h1>
       <b><big><big>Introduction</big></big></b><br>
       <br>
       Jetty can be configured to log requests and/or debugging information.
  An  implementation of a logging facility is provided with the release that
  can  send logged data to System.err, System.out, a named file or a specified 
  OutputStream.  &nbsp;If output is directed to a file, then log aging and 
 rollover is supported  and configurable. <br>
       <br>
       Jetty logging is designed to be flexible and thus it is possible to
 write   a custom logger and use it in place of the supplied logger. &nbsp;For
 example,   if Jetty is embedded in an application, then a custom logger
can  be written   to feed log events to application's native log mechanism.
&nbsp;All  loggers   are implementations of the  <a href="/javadoc/org/mortbay/util/LogSink.html">
         org.mortbay.util.LogSink</a> interface. The supplied logger is <a href="/javadoc/org/mortbay/util/OutputStreamLogSink.html">
        org.mortbay.util.OutputStreamLogSink</a>.<br>
       <br>
       Logging&nbsp;can&nbsp;be configured&nbsp;in&nbsp;four ways:<br>
             
<ul>
         <li>via the Jetty API</li>
         <li>via XML configuration files</li>
         <li>a Debug servlet supplied with the release</li>
         <li>JMX MBeans</li>
             
</ul>
       <br>
       The first two of these methods are covered in the sections below on
 <a href="#requests">     Logging Requests</a> and <a href="#debugging">Debugging</a>
  .<br>
       <br>
       The <a href="http://localhost:8081/Debug">Debug servlet</a> distributed
   with the Jetty <a href="/jetty/demos.html">demonstration servlets</a>
can  change the logging and debugging settings of a  running server. It is
configured  by the <tt>$JETTY_HOME/etc/admin.xml</tt>      file. As shipped,
it will start on port 8081. To login to it, use username   <tt>admin</tt>
 password <tt> admin</tt>.<br>
       <br>
       Finally, the JMX MBeans provided by the <a href="http://sourceforge.net/project/showfiles.php?group_id=7322">
       Jetty3Extra</a><a href="http://sourceforge.net/project/showfiles.php?group_id=7322">
        package</a> provides a mechanism to configure debugging and logging 
 at  runtime. It also provides statistics reporting. A description of this
 facility is, at the moment, beyond the scope  of this tutorial.<br>
       <br>
       <br>
                 
<p>   </p>
                 
<p> <big><big><b><a name="requests"></a>Logging Requests</b></big></big></p>

See <a href="/javadoc/org/mortbay/http/RequestLog.html">RequestLog</a> and 
<a href="/javadoc/org/mortbay/http/NCSARequestLog.html">NCSARequestLog</a>.
<p>
Requests can be logged at the server or context level by adding a
implementation of RequestLog to the server and/or context. NCSARequestLog is
an implementation of the defacto standard request log format in normal and
extended modes.
 <P>

       <big><big><br>
       <a name="debugging"></a><b>Debugging</b></big></big></b></font><br>
       <br>
          Debugging information is logged via the collection of&nbsp;<a href="/javadoc/org/mortbay/util/LogSink.html">
         org.mortbay.util.LogSink</a> instances configured   into the  static 
  instance of  <a href="/javadoc/org/mortbay/util/Log.html">    org.mortbay.util.Log</a>
     . The static instance can be configured via the  API, XML or java system 
  properties.<br>
     <br>
     For example, to configure a debug log file that will be rolled over
(as   indicated by the <tt>yyyy_mm_dd</tt> suffix indicates this):<br>
               
<table align=center border=0 cellpadding=2 cellspacing=0 width="90%">
<tbody>
<tr>
<td>
<small>
<pre>
java -DDEBUG -DLOG_FILE=./logs/debug_yyyy_mm_dd.log org.mortbay.jetty.Server
</pre>
</small>
             <b>Example: &nbsp; Setting the debug log file</b>
</td>
</tr>
</tbody>
</table>
             <br>
            <br>

     Jetty is instrumented with debugging statments provided by the <a href="/javadoc/org/mortbay/util/Code.html">
         org.mortbay.util.Code</a> class. Debugging directives control not
 only  the output file names, but also the verbosity of debug messages, and
 even  which classes may generate debug output.<br>
             <br>
     Debug information is categorized as one of the following types:<br>
             <br>
                                                 
        <table border="1" width="80%" cellpadding="4" cellspacing="2">
               <tbody>
                 <tr>
                   <td>ASSERT </td>
                   <td> reports the outcome of a programmatic assertion</td>
                 </tr>
                 <tr>
                   <td>WARN </td>
                   <td>a programmer initiated warning, intended to be viewed
  by technical staff</td>
                 </tr>
                 <tr>
                   <td>FAIL </td>
                   <td>a programmer initiated fatal error</td>
                 </tr>
                 <tr>
                   <td>DEBUG </td>
                   <td> general debug message</td>
                 </tr>
                                                           
          </tbody>                                             
        </table>
             <br>
             <br>
             <br>
     The Java System properties that control debugging are as follows: <br>
             <br>
             &nbsp;&nbsp; &nbsp;                                    
        <table border="1" width="80%" cellpadding="6" cellspacing="2">
               <tbody>
                 <tr>
                   <td width="20%">DEBUG</td>
                   <td>Only if this property is set will any debug output 
be  produced<br>
                   </td>
     </tr>
                 <tr>
                   <td>DEBUG_PATTERNS </td>
                   <td> Can be set to a comma separated list of strings.
In  this  case,&nbsp; debug output is only produced from those classes whose 
fully       qualified class name contains one of the strings as a substring. 
              <br>
                   <br>
     Eg.<br>
                                                                        
      
              <ul>
                     <li>"<tt>MyClass"</tt> matches <tt>"org.mortbay.util.MyClass"</tt>
     , <tt>"com.firm.stuff.MyClass"</tt></li>
                     <li>"com.firm" matches all classes in that package and 
 subpackages</li>
                     <li>"com.firm, org.mortbay.util.Threadpool" matches
all   com.firm classes the Threadpool class only<br>
                     </li>
                                                                        
      
              </ul>
                   </td>
                 </tr>
                 <tr>
                   <td>DEBUG_OPTIONS </td>
                   <td> String of one letter options:<br>
                                                                        
      
              <ul>
                     <li>'W'&nbsp; suppresses       warnings unless DEBUG 
is  on</li>
                     <li>'S' suppress stack frame dumps</li>
                                                                        
      
              </ul>
                   </td>
                 </tr>
                 <tr>
                   <td>DEBUG_VERBOSE </td>
                   <td> An integer value available to the programmer for
deciding   level of output verbosity. The Jetty code uses the following verbosity 
settings:<br>
                                                                        
      
              <ul>
                     <li>0</li>
                     <li>1</li>
                     <li>&gt;1</li>
                                                                        
      
              </ul>
                   </td>
                 </tr>
                                                           
          </tbody>                                             
        </table>
             <br>
             <br>
             <br>
     For example, to enable debugging from the classes "SocketListener" and 
 "ThreadedServer"  at a high level of verbosity :<br>
             <br>
                                                 
<table align=center border=0 cellpadding=2 cellspacing=0 width="90%">
<tbody>
<tr>
<td>
<small>
<pre>
java -DDEBUG \
&nbsp; &nbsp; &nbsp;-DLOG_FILE=./logs/debug_yyyy_mm_dd.log \
&nbsp; &nbsp; &nbsp;-DDEBUG_VERBOSE=99
&nbsp; &nbsp; &nbsp;-DDEBUG_PATTERNS="SocketListener,ThreadedServer"\
org.mortbay.jetty.Server
</pre>
</small>
                     <b> Example: &nbsp;Debug system properties</b>
</td>
</tr>
</tbody>
</table>
                     <br>
                     <br>
     Debugging can also be configured using the Jetty XML mechanism. The
same   example above can be presented as:                               
                                                          
                                                  
<table align=center border=0 cellpadding=2 cellspacing=0 width="90%">
<tbody>
<tr>
<td>
<small>
<pre>
&lt;Set name="Debug" class="org.mortbay.util.Code"
type="boolean"&gt;true&lt;/Set&gt;
  &lt;Set name="Verbose" class="org.mortbay.util.Code"
  type="int"&gt;99&lt;/Set&gt;
  &lt;Set name="DebugPatterns" class="org.mortbay.util.Code"
   type="String"&gt;"SocketListener,ThreadedServer"&lt;/Set&gt;
  &lt;Call name="instance" class="org.mortbay.util.Log"&gt;
    &lt;Call name="disableLog"/&gt;
    &lt;Call name="add"&gt; 
      &lt;Arg&gt;
        &lt;New class="org.mortbay.util.WriterLogSink"&gt;
          &lt;Arg&gt;&lt;SystemProperty name="jetty.home" 
                default="."/&gt;/logs/debug_yyyy_mm_dd.log&lt;/Arg&gt;
          &lt;Set name="RetainDays"&gt;90&lt;/Set&gt;
          &lt;Set name="Append"&gt;true&lt;/Set&gt;
          &lt;Call name="start"/&gt;
        &lt;/New&gt;
      &lt;/Arg&gt;
    &lt;/Call&gt;
  &lt;/Call&gt;
</pre>
</small>
</td>
</tr>
<tr>
<td align=center>
                        <b>XML Example: Debug set up</b>
</td>
</tr>
</tbody>
</table>
<br>
<br>
                                                                        
                                                                  
                                                                        
                                                                        
        
                          <table cellpadding="0" cellspacing="8" border="0" width="20%">
           <tbody>
             <tr>
               <td valign="middle" bgcolor="#ccccff"><small><a href="Server.html">
              BACK</a></small></td>
               <td valign="middle" bgcolor="#ccccff"><small><a href="index.html">
              INDEX</a></small></td>
               <td valign="middle" bgcolor="#ccccff"><small><a href="..">
    EXIT</a></small></td>
               <td valign="middle" bgcolor="#ccccff"><small><a href="XmlConfiguration.html">
              NEXT</a></small></td>
             </tr>
                                                                        
                                                                        
                   
                            </tbody>                                     
                                                                        
                            
                          </table>
                                                                        
                                                                        
  
                          </body>
                          </html>
